

<!DOCTYPE html>
<!--[if IE 8]><html class="no-js lt-ie9" lang="en" > <![endif]-->
<!--[if gt IE 8]><!--> <html class="no-js" lang="en" > <!--<![endif]-->
<head>
  <meta charset="utf-8">
  
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <meta name="Description" content="scikit-learn: machine learning in Python">

  
  <title>Developing scikit-learn estimators &mdash; scikit-learn 0.22 documentation</title>
  
  <link rel="canonical" href="http://scikit-learn.org/stable/developers/develop.html" />

  
  <link rel="shortcut icon" href="../_static/favicon.ico"/>
  

  <link rel="stylesheet" href="../_static/css/vendor/bootstrap.min.css" type="text/css" />
  <link rel="stylesheet" href="../_static/gallery.css" type="text/css" />
  <link rel="stylesheet" href="../_static/css/theme.css" type="text/css" />
<script id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script>
<script src="../_static/jquery.js"></script> 
</head>
<body>
<nav id="navbar" class="sk-docs-navbar navbar navbar-expand-md navbar-light bg-light py-0">
  <div class="container-fluid sk-docs-container px-0">
      <a class="navbar-brand py-0" href="../index.html">
        <img
          class="sk-brand-img"
          src="../_static/scikit-learn-logo-small.png"
          alt="logo"/>
      </a>
    <button
      id="sk-navbar-toggler"
      class="navbar-toggler"
      type="button"
      data-toggle="collapse"
      data-target="#navbarSupportedContent"
      aria-controls="navbarSupportedContent"
      aria-expanded="false"
      aria-label="Toggle navigation"
    >
      <span class="navbar-toggler-icon"></span>
    </button>

    <div class="sk-navbar-collapse collapse navbar-collapse" id="navbarSupportedContent">
      <ul class="navbar-nav mr-auto">
        <li class="nav-item">
          <a class="sk-nav-link nav-link" href="../install.html">Install</a>
        </li>
        <li class="nav-item">
          <a class="sk-nav-link nav-link" href="../user_guide.html">User Guide</a>
        </li>
        <li class="nav-item">
          <a class="sk-nav-link nav-link" href="../modules/classes.html">API</a>
        </li>
        <li class="nav-item">
          <a class="sk-nav-link nav-link" href="../auto_examples/index.html">Examples</a>
        </li>
        <li class="nav-item">
          <a class="sk-nav-link nav-link nav-more-item-mobile-items" href="../getting_started.html">Getting Started</a>
        </li>
        <li class="nav-item">
          <a class="sk-nav-link nav-link nav-more-item-mobile-items" href="../tutorial/index.html">Tutorial</a>
        </li>
        <li class="nav-item">
          <a class="sk-nav-link nav-link nav-more-item-mobile-items" href="../glossary.html">Glossary</a>
        </li>
        <li class="nav-item">
          <a class="sk-nav-link nav-link nav-more-item-mobile-items" href="index.html">Development</a>
        </li>
        <li class="nav-item">
          <a class="sk-nav-link nav-link nav-more-item-mobile-items" href="../faq.html">FAQ</a>
        </li>
        <li class="nav-item">
          <a class="sk-nav-link nav-link nav-more-item-mobile-items" href="../related_projects.html">Related packages</a>
        </li>
        <li class="nav-item">
          <a class="sk-nav-link nav-link nav-more-item-mobile-items" href="../roadmap.html">Roadmap</a>
        </li>
        <li class="nav-item">
          <a class="sk-nav-link nav-link nav-more-item-mobile-items" href="../about.html">About us</a>
        </li>
        <li class="nav-item">
          <a class="sk-nav-link nav-link nav-more-item-mobile-items" href="https://github.com/scikit-learn/scikit-learn">GitHub</a>
        </li>
        <li class="nav-item">
          <a class="sk-nav-link nav-link nav-more-item-mobile-items" href="https://scikit-learn.org/dev/versions.html">Other Versions</a>
        </li>
        <li class="nav-item dropdown nav-more-item-dropdown">
          <a class="sk-nav-link nav-link dropdown-toggle" href="#" id="navbarDropdown" role="button" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">More</a>
          <div class="dropdown-menu" aria-labelledby="navbarDropdown">
              <a class="sk-nav-dropdown-item dropdown-item" href="../getting_started.html">Getting Started</a>
              <a class="sk-nav-dropdown-item dropdown-item" href="../tutorial/index.html">Tutorial</a>
              <a class="sk-nav-dropdown-item dropdown-item" href="../glossary.html">Glossary</a>
              <a class="sk-nav-dropdown-item dropdown-item" href="index.html">Development</a>
              <a class="sk-nav-dropdown-item dropdown-item" href="../faq.html">FAQ</a>
              <a class="sk-nav-dropdown-item dropdown-item" href="../related_projects.html">Related packages</a>
              <a class="sk-nav-dropdown-item dropdown-item" href="../roadmap.html">Roadmap</a>
              <a class="sk-nav-dropdown-item dropdown-item" href="../about.html">About us</a>
              <a class="sk-nav-dropdown-item dropdown-item" href="https://github.com/scikit-learn/scikit-learn">GitHub</a>
              <a class="sk-nav-dropdown-item dropdown-item" href="https://scikit-learn.org/dev/versions.html">Other Versions</a>
          </div>
        </li>
      </ul>
      <div id="searchbox" role="search">
          <div class="searchformwrapper">
          <form class="search" action="../search.html" method="get">
            <input class="sk-search-text-input" type="text" name="q" aria-labelledby="searchlabel" />
            <input class="sk-search-text-btn" type="submit" value="Go" />
          </form>
          </div>
      </div>
    </div>
  </div>
</nav>
<div class="d-flex" id="sk-doc-wrapper">
    <input type="checkbox" name="sk-toggle-checkbox" id="sk-toggle-checkbox">
    <label id="sk-sidemenu-toggle" class="sk-btn-toggle-toc btn sk-btn-primary" for="sk-toggle-checkbox">Toggle Menu</label>
    <div id="sk-sidebar-wrapper" class="border-right">
      <div class="sk-sidebar-toc-wrapper">
        <div class="sk-sidebar-toc-logo">
          <a href="../index.html">
            <img
              class="sk-brand-img"
              src="../_static/scikit-learn-logo-small.png"
              alt="logo"/>
          </a>
        </div>
        <div class="btn-group w-100 mb-2" role="group" aria-label="rellinks">
            <a href="contributing.html" role="button" class="btn sk-btn-rellink py-1" sk-rellink-tooltip="Contributing">Prev</a><a href="index.html" role="button" class="btn sk-btn-rellink py-1" sk-rellink-tooltip="Developer’s Guide">Up</a>
            <a href="tips.html" role="button" class="btn sk-btn-rellink py-1" sk-rellink-tooltip="Developers’ Tips and Tricks">Next</a>
        </div>
        <div class="alert alert-danger p-1 mb-2" role="alert">
          <p class="text-center mb-0">
          <strong>scikit-learn 0.22</strong><br/>
          <a href="http://scikit-learn.org/dev/versions.html">Other versions</a>
          </p>
        </div>
        <div class="alert alert-warning p-1 mb-2" role="alert">
          <p class="text-center mb-0">
            Please <a class="font-weight-bold" href="../about.html#citing-scikit-learn"><string>cite us</string></a> if you use the software.
          </p>
        </div>
          <div class="sk-sidebar-toc">
            <ul>
<li><a class="reference internal" href="#">Developing scikit-learn estimators</a><ul>
<li><a class="reference internal" href="#apis-of-scikit-learn-objects">APIs of scikit-learn objects</a><ul>
<li><a class="reference internal" href="#different-objects">Different objects</a></li>
<li><a class="reference internal" href="#estimators">Estimators</a><ul>
<li><a class="reference internal" href="#instantiation">Instantiation</a></li>
<li><a class="reference internal" href="#fitting">Fitting</a></li>
<li><a class="reference internal" href="#estimated-attributes">Estimated Attributes</a></li>
<li><a class="reference internal" href="#optional-arguments">Optional Arguments</a></li>
<li><a class="reference internal" href="#pairwise-attributes">Pairwise Attributes</a></li>
</ul>
</li>
</ul>
</li>
<li><a class="reference internal" href="#rolling-your-own-estimator">Rolling your own estimator</a><ul>
<li><a class="reference internal" href="#get-params-and-set-params">get_params and set_params</a></li>
<li><a class="reference internal" href="#parameters-and-init">Parameters and init</a></li>
<li><a class="reference internal" href="#cloning">Cloning</a></li>
<li><a class="reference internal" href="#pipeline-compatibility">Pipeline compatibility</a></li>
<li><a class="reference internal" href="#estimator-types">Estimator types</a></li>
<li><a class="reference internal" href="#specific-models">Specific models</a></li>
<li><a class="reference internal" href="#estimator-tags">Estimator Tags</a></li>
</ul>
</li>
<li><a class="reference internal" href="#coding-guidelines">Coding guidelines</a><ul>
<li><a class="reference internal" href="#input-validation">Input validation</a></li>
<li><a class="reference internal" href="#random-numbers">Random Numbers</a></li>
</ul>
</li>
</ul>
</li>
</ul>

          </div>
      </div>
    </div>
    <div id="sk-page-content-wrapper">
      <div class="sk-page-content container-fluid body px-md-3" role="main">
        
  <div class="section" id="developing-scikit-learn-estimators">
<span id="develop"></span><h1>Developing scikit-learn estimators<a class="headerlink" href="#developing-scikit-learn-estimators" title="Permalink to this headline">¶</a></h1>
<p>Whether you are proposing an estimator for inclusion in scikit-learn,
developing a separate package compatible with scikit-learn, or
implementing custom components for your own projects, this chapter
details how to develop objects that safely interact with scikit-learn
Pipelines and model selection tools.</p>
<div class="section" id="apis-of-scikit-learn-objects">
<span id="api-overview"></span><h2>APIs of scikit-learn objects<a class="headerlink" href="#apis-of-scikit-learn-objects" title="Permalink to this headline">¶</a></h2>
<p>To have a uniform API, we try to have a common basic API for all the
objects. In addition, to avoid the proliferation of framework code, we
try to adopt simple conventions and limit to a minimum the number of
methods an object must implement.</p>
<p>Elements of the scikit-learn API are described more definitively in the
<a class="reference internal" href="../glossary.html#glossary"><span class="std std-ref">Glossary of Common Terms and API Elements</span></a>.</p>
<div class="section" id="different-objects">
<h3>Different objects<a class="headerlink" href="#different-objects" title="Permalink to this headline">¶</a></h3>
<p>The main objects in scikit-learn are (one class can implement
multiple interfaces):</p>
<dl class="field-list">
<dt class="field-odd">Estimator</dt>
<dd class="field-odd"><p>The base object, implements a <code class="docutils literal notranslate"><span class="pre">fit</span></code> method to learn from data, either:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">estimator</span> <span class="o">=</span> <span class="n">estimator</span><span class="o">.</span><span class="n">fit</span><span class="p">(</span><span class="n">data</span><span class="p">,</span> <span class="n">targets</span><span class="p">)</span>
</pre></div>
</div>
<p>or:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">estimator</span> <span class="o">=</span> <span class="n">estimator</span><span class="o">.</span><span class="n">fit</span><span class="p">(</span><span class="n">data</span><span class="p">)</span>
</pre></div>
</div>
</dd>
<dt class="field-even">Predictor</dt>
<dd class="field-even"><p>For supervised learning, or some unsupervised problems, implements:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">prediction</span> <span class="o">=</span> <span class="n">predictor</span><span class="o">.</span><span class="n">predict</span><span class="p">(</span><span class="n">data</span><span class="p">)</span>
</pre></div>
</div>
<p>Classification algorithms usually also offer a way to quantify certainty
of a prediction, either using <code class="docutils literal notranslate"><span class="pre">decision_function</span></code> or <code class="docutils literal notranslate"><span class="pre">predict_proba</span></code>:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">probability</span> <span class="o">=</span> <span class="n">predictor</span><span class="o">.</span><span class="n">predict_proba</span><span class="p">(</span><span class="n">data</span><span class="p">)</span>
</pre></div>
</div>
</dd>
<dt class="field-odd">Transformer</dt>
<dd class="field-odd"><p>For filtering or modifying the data, in a supervised or unsupervised
way, implements:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">new_data</span> <span class="o">=</span> <span class="n">transformer</span><span class="o">.</span><span class="n">transform</span><span class="p">(</span><span class="n">data</span><span class="p">)</span>
</pre></div>
</div>
<p>When fitting and transforming can be performed much more efficiently
together than separately, implements:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">new_data</span> <span class="o">=</span> <span class="n">transformer</span><span class="o">.</span><span class="n">fit_transform</span><span class="p">(</span><span class="n">data</span><span class="p">)</span>
</pre></div>
</div>
</dd>
<dt class="field-even">Model</dt>
<dd class="field-even"><p>A model that can give a <a class="reference external" href="https://en.wikipedia.org/wiki/Goodness_of_fit">goodness of fit</a>
measure or a likelihood of unseen data, implements (higher is better):</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">score</span> <span class="o">=</span> <span class="n">model</span><span class="o">.</span><span class="n">score</span><span class="p">(</span><span class="n">data</span><span class="p">)</span>
</pre></div>
</div>
</dd>
</dl>
</div>
<div class="section" id="estimators">
<h3>Estimators<a class="headerlink" href="#estimators" title="Permalink to this headline">¶</a></h3>
<p>The API has one predominant object: the estimator. A estimator is an
object that fits a model based on some training data and is capable of
inferring some properties on new data. It can be, for instance, a
classifier or a regressor. All estimators implement the fit method:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">estimator</span><span class="o">.</span><span class="n">fit</span><span class="p">(</span><span class="n">X</span><span class="p">,</span> <span class="n">y</span><span class="p">)</span>
</pre></div>
</div>
<p>All built-in estimators also have a <code class="docutils literal notranslate"><span class="pre">set_params</span></code> method, which sets
data-independent parameters (overriding previous parameter values passed
to <code class="docutils literal notranslate"><span class="pre">__init__</span></code>).</p>
<p>All estimators in the main scikit-learn codebase should inherit from
<code class="docutils literal notranslate"><span class="pre">sklearn.base.BaseEstimator</span></code>.</p>
<div class="section" id="instantiation">
<h4>Instantiation<a class="headerlink" href="#instantiation" title="Permalink to this headline">¶</a></h4>
<p>This concerns the creation of an object. The object’s <code class="docutils literal notranslate"><span class="pre">__init__</span></code> method
might accept constants as arguments that determine the estimator’s behavior
(like the C constant in SVMs). It should not, however, take the actual training
data as an argument, as this is left to the <code class="docutils literal notranslate"><span class="pre">fit()</span></code> method:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">clf2</span> <span class="o">=</span> <span class="n">SVC</span><span class="p">(</span><span class="n">C</span><span class="o">=</span><span class="mf">2.3</span><span class="p">)</span>
<span class="n">clf3</span> <span class="o">=</span> <span class="n">SVC</span><span class="p">([[</span><span class="mi">1</span><span class="p">,</span> <span class="mi">2</span><span class="p">],</span> <span class="p">[</span><span class="mi">2</span><span class="p">,</span> <span class="mi">3</span><span class="p">]],</span> <span class="p">[</span><span class="o">-</span><span class="mi">1</span><span class="p">,</span> <span class="mi">1</span><span class="p">])</span> <span class="c1"># WRONG!</span>
</pre></div>
</div>
<p>The arguments accepted by <code class="docutils literal notranslate"><span class="pre">__init__</span></code> should all be keyword arguments
with a default value. In other words, a user should be able to instantiate
an estimator without passing any arguments to it. The arguments should all
correspond to hyperparameters describing the model or the optimisation
problem the estimator tries to solve. These initial arguments (or parameters)
are always remembered by the estimator.
Also note that they should not be documented under the “Attributes” section,
but rather under the “Parameters” section for that estimator.</p>
<p>In addition, <strong>every keyword argument accepted by</strong> <code class="docutils literal notranslate"><span class="pre">__init__</span></code> <strong>should
correspond to an attribute on the instance</strong>. Scikit-learn relies on this to
find the relevant attributes to set on an estimator when doing model selection.</p>
<p>To summarize, an <code class="docutils literal notranslate"><span class="pre">__init__</span></code> should look like:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="k">def</span> <span class="fm">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">param1</span><span class="o">=</span><span class="mi">1</span><span class="p">,</span> <span class="n">param2</span><span class="o">=</span><span class="mi">2</span><span class="p">):</span>
    <span class="bp">self</span><span class="o">.</span><span class="n">param1</span> <span class="o">=</span> <span class="n">param1</span>
    <span class="bp">self</span><span class="o">.</span><span class="n">param2</span> <span class="o">=</span> <span class="n">param2</span>
</pre></div>
</div>
<p>There should be no logic, not even input validation,
and the parameters should not be changed.
The corresponding logic should be put where the parameters are used,
typically in <code class="docutils literal notranslate"><span class="pre">fit</span></code>.
The following is wrong:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="k">def</span> <span class="fm">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">param1</span><span class="o">=</span><span class="mi">1</span><span class="p">,</span> <span class="n">param2</span><span class="o">=</span><span class="mi">2</span><span class="p">,</span> <span class="n">param3</span><span class="o">=</span><span class="mi">3</span><span class="p">):</span>
    <span class="c1"># WRONG: parameters should not be modified</span>
    <span class="k">if</span> <span class="n">param1</span> <span class="o">&gt;</span> <span class="mi">1</span><span class="p">:</span>
        <span class="n">param2</span> <span class="o">+=</span> <span class="mi">1</span>
    <span class="bp">self</span><span class="o">.</span><span class="n">param1</span> <span class="o">=</span> <span class="n">param1</span>
    <span class="c1"># WRONG: the object&#39;s attributes should have exactly the name of</span>
    <span class="c1"># the argument in the constructor</span>
    <span class="bp">self</span><span class="o">.</span><span class="n">param3</span> <span class="o">=</span> <span class="n">param2</span>
</pre></div>
</div>
<p>The reason for postponing the validation is that the same validation
would have to be performed in <code class="docutils literal notranslate"><span class="pre">set_params</span></code>,
which is used in algorithms like <code class="docutils literal notranslate"><span class="pre">GridSearchCV</span></code>.</p>
</div>
<div class="section" id="fitting">
<h4>Fitting<a class="headerlink" href="#fitting" title="Permalink to this headline">¶</a></h4>
<p>The next thing you will probably want to do is to estimate some
parameters in the model. This is implemented in the <code class="docutils literal notranslate"><span class="pre">fit()</span></code> method.</p>
<p>The <code class="docutils literal notranslate"><span class="pre">fit()</span></code> method takes the training data as arguments, which can be one
array in the case of unsupervised learning, or two arrays in the case
of supervised learning.</p>
<p>Note that the model is fitted using X and y, but the object holds no
reference to X and y. There are, however, some exceptions to this, as in
the case of precomputed kernels where this data must be stored for use by
the predict method.</p>
<table class="docutils align-default">
<colgroup>
<col style="width: 19%" />
<col style="width: 81%" />
</colgroup>
<thead>
<tr class="row-odd"><th class="head"><p>Parameters</p></th>
<th class="head"></th>
</tr>
</thead>
<tbody>
<tr class="row-even"><td><p>X</p></td>
<td><p>array-like, shape (n_samples, n_features)</p></td>
</tr>
<tr class="row-odd"><td><p>y</p></td>
<td><p>array, shape (n_samples,)</p></td>
</tr>
<tr class="row-even"><td><p>kwargs</p></td>
<td><p>optional data-dependent parameters.</p></td>
</tr>
</tbody>
</table>
<p><code class="docutils literal notranslate"><span class="pre">X.shape[0]</span></code> should be the same as <code class="docutils literal notranslate"><span class="pre">y.shape[0]</span></code>. If this requisite
is not met, an exception of type <code class="docutils literal notranslate"><span class="pre">ValueError</span></code> should be raised.</p>
<p><code class="docutils literal notranslate"><span class="pre">y</span></code> might be ignored in the case of unsupervised learning. However, to
make it possible to use the estimator as part of a pipeline that can
mix both supervised and unsupervised transformers, even unsupervised
estimators need to accept a <code class="docutils literal notranslate"><span class="pre">y=None</span></code> keyword argument in
the second position that is just ignored by the estimator.
For the same reason, <code class="docutils literal notranslate"><span class="pre">fit_predict</span></code>, <code class="docutils literal notranslate"><span class="pre">fit_transform</span></code>, <code class="docutils literal notranslate"><span class="pre">score</span></code>
and <code class="docutils literal notranslate"><span class="pre">partial_fit</span></code> methods need to accept a <code class="docutils literal notranslate"><span class="pre">y</span></code> argument in
the second place if they are implemented.</p>
<p>The method should return the object (<code class="docutils literal notranslate"><span class="pre">self</span></code>). This pattern is useful
to be able to implement quick one liners in an IPython session such as:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">y_predicted</span> <span class="o">=</span> <span class="n">SVC</span><span class="p">(</span><span class="n">C</span><span class="o">=</span><span class="mi">100</span><span class="p">)</span><span class="o">.</span><span class="n">fit</span><span class="p">(</span><span class="n">X_train</span><span class="p">,</span> <span class="n">y_train</span><span class="p">)</span><span class="o">.</span><span class="n">predict</span><span class="p">(</span><span class="n">X_test</span><span class="p">)</span>
</pre></div>
</div>
<p>Depending on the nature of the algorithm, <code class="docutils literal notranslate"><span class="pre">fit</span></code> can sometimes also
accept additional keywords arguments. However, any parameter that can
have a value assigned prior to having access to the data should be an
<code class="docutils literal notranslate"><span class="pre">__init__</span></code> keyword argument. <strong>fit parameters should be restricted
to directly data dependent variables</strong>. For instance a Gram matrix or
an affinity matrix which are precomputed from the data matrix <code class="docutils literal notranslate"><span class="pre">X</span></code> are
data dependent. A tolerance stopping criterion <code class="docutils literal notranslate"><span class="pre">tol</span></code> is not directly
data dependent (although the optimal value according to some scoring
function probably is).</p>
<p>When <code class="docutils literal notranslate"><span class="pre">fit</span></code> is called, any previous call to <code class="docutils literal notranslate"><span class="pre">fit</span></code> should be ignored. In
general, calling <code class="docutils literal notranslate"><span class="pre">estimator.fit(X1)</span></code> and then <code class="docutils literal notranslate"><span class="pre">estimator.fit(X2)</span></code> should
be the same as only calling <code class="docutils literal notranslate"><span class="pre">estimator.fit(X2)</span></code>. However, this may not be
true in practice when <code class="docutils literal notranslate"><span class="pre">fit</span></code> depends on some random process, see
<a class="reference internal" href="../glossary.html#term-random-state"><span class="xref std std-term">random_state</span></a>. Another exception to this rule is when the
hyper-parameter <code class="docutils literal notranslate"><span class="pre">warm_start</span></code> is set to <code class="docutils literal notranslate"><span class="pre">True</span></code> for estimators that
support it. <code class="docutils literal notranslate"><span class="pre">warm_start=True</span></code> means that the previous state of the
trainable parameters of the estimator are reused instead of using the
default initialization strategy.</p>
</div>
<div class="section" id="estimated-attributes">
<h4>Estimated Attributes<a class="headerlink" href="#estimated-attributes" title="Permalink to this headline">¶</a></h4>
<p>Attributes that have been estimated from the data must always have a name
ending with trailing underscore, for example the coefficients of
some regression estimator would be stored in a <code class="docutils literal notranslate"><span class="pre">coef_</span></code> attribute after
<code class="docutils literal notranslate"><span class="pre">fit</span></code> has been called.</p>
<p>The estimated attributes are expected to be overridden when you call <code class="docutils literal notranslate"><span class="pre">fit</span></code>
a second time.</p>
</div>
<div class="section" id="optional-arguments">
<h4>Optional Arguments<a class="headerlink" href="#optional-arguments" title="Permalink to this headline">¶</a></h4>
<p>In iterative algorithms, the number of iterations should be specified by
an integer called <code class="docutils literal notranslate"><span class="pre">n_iter</span></code>.</p>
</div>
<div class="section" id="pairwise-attributes">
<h4>Pairwise Attributes<a class="headerlink" href="#pairwise-attributes" title="Permalink to this headline">¶</a></h4>
<p>An estimator that accept <code class="docutils literal notranslate"><span class="pre">X</span></code> of shape <code class="docutils literal notranslate"><span class="pre">(n_samples,</span> <span class="pre">n_samples)</span></code> and defines
a <a class="reference internal" href="../glossary.html#term-pairwise"><span class="xref std std-term">_pairwise</span></a> property equal to <code class="docutils literal notranslate"><span class="pre">True</span></code> allows for cross-validation of
the dataset, e.g. when <code class="docutils literal notranslate"><span class="pre">X</span></code> is a precomputed kernel matrix. Specifically,
the <a class="reference internal" href="../glossary.html#term-pairwise"><span class="xref std std-term">_pairwise</span></a> property is used by <code class="docutils literal notranslate"><span class="pre">utils.metaestimators._safe_split</span></code>
to slice rows and columns.</p>
</div>
</div>
</div>
<div class="section" id="rolling-your-own-estimator">
<span id="id1"></span><h2>Rolling your own estimator<a class="headerlink" href="#rolling-your-own-estimator" title="Permalink to this headline">¶</a></h2>
<p>If you want to implement a new estimator that is scikit-learn-compatible,
whether it is just for you or for contributing it to scikit-learn, there are
several internals of scikit-learn that you should be aware of in addition to
the scikit-learn API outlined above. You can check whether your estimator
adheres to the scikit-learn interface and standards by running
<a class="reference internal" href="../modules/generated/sklearn.utils.estimator_checks.check_estimator.html#sklearn.utils.estimator_checks.check_estimator" title="sklearn.utils.estimator_checks.check_estimator"><code class="xref py py-func docutils literal notranslate"><span class="pre">utils.estimator_checks.check_estimator</span></code></a> on the class:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="kn">from</span> <span class="nn">sklearn.utils.estimator_checks</span> <span class="kn">import</span> <span class="n">check_estimator</span>
<span class="gp">&gt;&gt;&gt; </span><span class="kn">from</span> <span class="nn">sklearn.svm</span> <span class="kn">import</span> <span class="n">LinearSVC</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">check_estimator</span><span class="p">(</span><span class="n">LinearSVC</span><span class="p">)</span>  <span class="c1"># passes</span>
</pre></div>
</div>
<p>The main motivation to make a class compatible to the scikit-learn estimator
interface might be that you want to use it together with model evaluation and
selection tools such as <a class="reference internal" href="../modules/generated/sklearn.model_selection.GridSearchCV.html#sklearn.model_selection.GridSearchCV" title="sklearn.model_selection.GridSearchCV"><code class="xref py py-class docutils literal notranslate"><span class="pre">model_selection.GridSearchCV</span></code></a> and
<a class="reference internal" href="../modules/generated/sklearn.pipeline.Pipeline.html#sklearn.pipeline.Pipeline" title="sklearn.pipeline.Pipeline"><code class="xref py py-class docutils literal notranslate"><span class="pre">pipeline.Pipeline</span></code></a>.</p>
<p>Setting <code class="docutils literal notranslate"><span class="pre">generate_only=True</span></code> returns a generator that yields (estimator, check)
tuples where the check can be called independently from each other, i.e.
<code class="docutils literal notranslate"><span class="pre">check(estimator)</span></code>. This allows all checks to be run independently and report
the checks that are failing. scikit-learn provides a pytest specific decorator,
<code class="xref py py-func docutils literal notranslate"><span class="pre">parametrize_with_checks</span></code>, making it easier to test
multiple estimators:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">sklearn.utils.estimator_checks</span> <span class="kn">import</span> <span class="n">parametrize_with_checks</span>
<span class="kn">from</span> <span class="nn">sklearn.linear_model</span> <span class="kn">import</span> <span class="n">LogisticRegression</span>
<span class="kn">from</span> <span class="nn">sklearn.tree</span> <span class="kn">import</span> <span class="n">DecisionTreeRegressor</span>

<span class="nd">@parametrize_with_checks</span><span class="p">([</span><span class="n">LogisticRegression</span><span class="p">,</span> <span class="n">DecisionTreeRegressor</span><span class="p">])</span>
<span class="k">def</span> <span class="nf">test_sklearn_compatible_estimator</span><span class="p">(</span><span class="n">estimator</span><span class="p">,</span> <span class="n">check</span><span class="p">):</span>
    <span class="n">check</span><span class="p">(</span><span class="n">estimator</span><span class="p">)</span>
</pre></div>
</div>
<p>This decorator sets the <code class="docutils literal notranslate"><span class="pre">id</span></code> keyword in <code class="docutils literal notranslate"><span class="pre">pytest.mark.parameterize</span></code> exposing
the name of the underlying estimator and check in the test name. This allows
<code class="docutils literal notranslate"><span class="pre">pytest</span> <span class="pre">-k</span></code> to be used to specify which tests to run.</p>
<p>Before detailing the required interface below, we describe two ways to achieve
the correct interface more easily.</p>
<div class="topic">
<p class="topic-title">Project template:</p>
<p>We provide a <a class="reference external" href="https://github.com/scikit-learn-contrib/project-template/">project template</a>
which helps in the creation of Python packages containing scikit-learn compatible estimators.
It provides:</p>
<ul class="simple">
<li><p>an initial git repository with Python package directory structure</p></li>
<li><p>a template of a scikit-learn estimator</p></li>
<li><p>an initial test suite including use of <code class="docutils literal notranslate"><span class="pre">check_estimator</span></code></p></li>
<li><p>directory structures and scripts to compile documentation and example
galleries</p></li>
<li><p>scripts to manage continuous integration (testing on Linux and Windows)</p></li>
<li><p>instructions from getting started to publishing on <a class="reference external" href="https://pypi.org/">PyPi</a></p></li>
</ul>
</div>
<div class="topic">
<p class="topic-title"><code class="docutils literal notranslate"><span class="pre">BaseEstimator</span></code> and mixins:</p>
<p>We tend to use “duck typing”, so building an estimator which follows
the API suffices for compatibility, without needing to inherit from or
even import any scikit-learn classes.</p>
<p>However, if a dependency on scikit-learn is acceptable in your code,
you can prevent a lot of boilerplate code
by deriving a class from <code class="docutils literal notranslate"><span class="pre">BaseEstimator</span></code>
and optionally the mixin classes in <code class="docutils literal notranslate"><span class="pre">sklearn.base</span></code>.
For example, below is a custom classifier, with more examples included
in the scikit-learn-contrib
<a class="reference external" href="https://github.com/scikit-learn-contrib/project-template/blob/master/skltemplate/_template.py">project template</a>.</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="kn">import</span> <span class="nn">numpy</span> <span class="k">as</span> <span class="nn">np</span>
<span class="gp">&gt;&gt;&gt; </span><span class="kn">from</span> <span class="nn">sklearn.base</span> <span class="kn">import</span> <span class="n">BaseEstimator</span><span class="p">,</span> <span class="n">ClassifierMixin</span>
<span class="gp">&gt;&gt;&gt; </span><span class="kn">from</span> <span class="nn">sklearn.utils.validation</span> <span class="kn">import</span> <span class="n">check_X_y</span><span class="p">,</span> <span class="n">check_array</span><span class="p">,</span> <span class="n">check_is_fitted</span>
<span class="gp">&gt;&gt;&gt; </span><span class="kn">from</span> <span class="nn">sklearn.utils.multiclass</span> <span class="kn">import</span> <span class="n">unique_labels</span>
<span class="gp">&gt;&gt;&gt; </span><span class="kn">from</span> <span class="nn">sklearn.metrics</span> <span class="kn">import</span> <span class="n">euclidean_distances</span>
<span class="gp">&gt;&gt;&gt; </span><span class="k">class</span> <span class="nc">TemplateClassifier</span><span class="p">(</span><span class="n">BaseEstimator</span><span class="p">,</span> <span class="n">ClassifierMixin</span><span class="p">):</span>
<span class="gp">...</span>
<span class="gp">... </span>    <span class="k">def</span> <span class="fm">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">demo_param</span><span class="o">=</span><span class="s1">&#39;demo&#39;</span><span class="p">):</span>
<span class="gp">... </span>        <span class="bp">self</span><span class="o">.</span><span class="n">demo_param</span> <span class="o">=</span> <span class="n">demo_param</span>
<span class="gp">...</span>
<span class="gp">... </span>    <span class="k">def</span> <span class="nf">fit</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">X</span><span class="p">,</span> <span class="n">y</span><span class="p">):</span>
<span class="gp">...</span>
<span class="gp">... </span>        <span class="c1"># Check that X and y have correct shape</span>
<span class="gp">... </span>        <span class="n">X</span><span class="p">,</span> <span class="n">y</span> <span class="o">=</span> <span class="n">check_X_y</span><span class="p">(</span><span class="n">X</span><span class="p">,</span> <span class="n">y</span><span class="p">)</span>
<span class="gp">... </span>        <span class="c1"># Store the classes seen during fit</span>
<span class="gp">... </span>        <span class="bp">self</span><span class="o">.</span><span class="n">classes_</span> <span class="o">=</span> <span class="n">unique_labels</span><span class="p">(</span><span class="n">y</span><span class="p">)</span>
<span class="gp">...</span>
<span class="gp">... </span>        <span class="bp">self</span><span class="o">.</span><span class="n">X_</span> <span class="o">=</span> <span class="n">X</span>
<span class="gp">... </span>        <span class="bp">self</span><span class="o">.</span><span class="n">y_</span> <span class="o">=</span> <span class="n">y</span>
<span class="gp">... </span>        <span class="c1"># Return the classifier</span>
<span class="gp">... </span>        <span class="k">return</span> <span class="bp">self</span>
<span class="gp">...</span>
<span class="gp">... </span>    <span class="k">def</span> <span class="nf">predict</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">X</span><span class="p">):</span>
<span class="gp">...</span>
<span class="gp">... </span>        <span class="c1"># Check is fit had been called</span>
<span class="gp">... </span>        <span class="n">check_is_fitted</span><span class="p">(</span><span class="bp">self</span><span class="p">)</span>
<span class="gp">...</span>
<span class="gp">... </span>        <span class="c1"># Input validation</span>
<span class="gp">... </span>        <span class="n">X</span> <span class="o">=</span> <span class="n">check_array</span><span class="p">(</span><span class="n">X</span><span class="p">)</span>
<span class="gp">...</span>
<span class="gp">... </span>        <span class="n">closest</span> <span class="o">=</span> <span class="n">np</span><span class="o">.</span><span class="n">argmin</span><span class="p">(</span><span class="n">euclidean_distances</span><span class="p">(</span><span class="n">X</span><span class="p">,</span> <span class="bp">self</span><span class="o">.</span><span class="n">X_</span><span class="p">),</span> <span class="n">axis</span><span class="o">=</span><span class="mi">1</span><span class="p">)</span>
<span class="gp">... </span>        <span class="k">return</span> <span class="bp">self</span><span class="o">.</span><span class="n">y_</span><span class="p">[</span><span class="n">closest</span><span class="p">]</span>
</pre></div>
</div>
</div>
<div class="section" id="get-params-and-set-params">
<h3>get_params and set_params<a class="headerlink" href="#get-params-and-set-params" title="Permalink to this headline">¶</a></h3>
<p>All scikit-learn estimators have <code class="docutils literal notranslate"><span class="pre">get_params</span></code> and <code class="docutils literal notranslate"><span class="pre">set_params</span></code> functions.
The <code class="docutils literal notranslate"><span class="pre">get_params</span></code> function takes no arguments and returns a dict of the
<code class="docutils literal notranslate"><span class="pre">__init__</span></code> parameters of the estimator, together with their values.
It must take one keyword argument, <code class="docutils literal notranslate"><span class="pre">deep</span></code>,
which receives a boolean value that determines
whether the method should return the parameters of sub-estimators
(for most estimators, this can be ignored).
The default value for <code class="docutils literal notranslate"><span class="pre">deep</span></code> should be true.</p>
<p>The <code class="docutils literal notranslate"><span class="pre">set_params</span></code> on the other hand takes as input a dict of the form
<code class="docutils literal notranslate"><span class="pre">'parameter':</span> <span class="pre">value</span></code> and sets the parameter of the estimator using this dict.
Return value must be estimator itself.</p>
<p>While the <code class="docutils literal notranslate"><span class="pre">get_params</span></code> mechanism is not essential (see <a class="reference internal" href="#cloning"><span class="std std-ref">Cloning</span></a> below),
the <code class="docutils literal notranslate"><span class="pre">set_params</span></code> function is necessary as it is used to set parameters during
grid searches.</p>
<p>The easiest way to implement these functions, and to get a sensible
<code class="docutils literal notranslate"><span class="pre">__repr__</span></code> method, is to inherit from <code class="docutils literal notranslate"><span class="pre">sklearn.base.BaseEstimator</span></code>. If you
do not want to make your code dependent on scikit-learn, the easiest way to
implement the interface is:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="k">def</span> <span class="nf">get_params</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">deep</span><span class="o">=</span><span class="kc">True</span><span class="p">):</span>
    <span class="c1"># suppose this estimator has parameters &quot;alpha&quot; and &quot;recursive&quot;</span>
    <span class="k">return</span> <span class="p">{</span><span class="s2">&quot;alpha&quot;</span><span class="p">:</span> <span class="bp">self</span><span class="o">.</span><span class="n">alpha</span><span class="p">,</span> <span class="s2">&quot;recursive&quot;</span><span class="p">:</span> <span class="bp">self</span><span class="o">.</span><span class="n">recursive</span><span class="p">}</span>

<span class="k">def</span> <span class="nf">set_params</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="o">**</span><span class="n">parameters</span><span class="p">):</span>
    <span class="k">for</span> <span class="n">parameter</span><span class="p">,</span> <span class="n">value</span> <span class="ow">in</span> <span class="n">parameters</span><span class="o">.</span><span class="n">items</span><span class="p">():</span>
        <span class="nb">setattr</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">parameter</span><span class="p">,</span> <span class="n">value</span><span class="p">)</span>
    <span class="k">return</span> <span class="bp">self</span>
</pre></div>
</div>
</div>
<div class="section" id="parameters-and-init">
<h3>Parameters and init<a class="headerlink" href="#parameters-and-init" title="Permalink to this headline">¶</a></h3>
<p>As <a class="reference internal" href="../modules/generated/sklearn.model_selection.GridSearchCV.html#sklearn.model_selection.GridSearchCV" title="sklearn.model_selection.GridSearchCV"><code class="xref py py-class docutils literal notranslate"><span class="pre">model_selection.GridSearchCV</span></code></a> uses <code class="docutils literal notranslate"><span class="pre">set_params</span></code>
to apply parameter setting to estimators,
it is essential that calling <code class="docutils literal notranslate"><span class="pre">set_params</span></code> has the same effect
as setting parameters using the <code class="docutils literal notranslate"><span class="pre">__init__</span></code> method.
The easiest and recommended way to accomplish this is to
<strong>not do any parameter validation in</strong> <code class="docutils literal notranslate"><span class="pre">__init__</span></code>.
All logic behind estimator parameters,
like translating string arguments into functions, should be done in <code class="docutils literal notranslate"><span class="pre">fit</span></code>.</p>
<p>Also it is expected that parameters with trailing <code class="docutils literal notranslate"><span class="pre">_</span></code> are <strong>not to be set
inside the</strong> <code class="docutils literal notranslate"><span class="pre">__init__</span></code> <strong>method</strong>. All and only the public attributes set by
fit have a trailing <code class="docutils literal notranslate"><span class="pre">_</span></code>. As a result the existence of parameters with
trailing <code class="docutils literal notranslate"><span class="pre">_</span></code> is used to check if the estimator has been fitted.</p>
</div>
<div class="section" id="cloning">
<span id="id2"></span><h3>Cloning<a class="headerlink" href="#cloning" title="Permalink to this headline">¶</a></h3>
<p>For use with the <code class="xref py py-mod docutils literal notranslate"><span class="pre">model_selection</span></code> module,
an estimator must support the <code class="docutils literal notranslate"><span class="pre">base.clone</span></code> function to replicate an estimator.
This can be done by providing a <code class="docutils literal notranslate"><span class="pre">get_params</span></code> method.
If <code class="docutils literal notranslate"><span class="pre">get_params</span></code> is present, then <code class="docutils literal notranslate"><span class="pre">clone(estimator)</span></code> will be an instance of
<code class="docutils literal notranslate"><span class="pre">type(estimator)</span></code> on which <code class="docutils literal notranslate"><span class="pre">set_params</span></code> has been called with clones of
the result of <code class="docutils literal notranslate"><span class="pre">estimator.get_params()</span></code>.</p>
<p>Objects that do not provide this method will be deep-copied
(using the Python standard function <code class="docutils literal notranslate"><span class="pre">copy.deepcopy</span></code>)
if <code class="docutils literal notranslate"><span class="pre">safe=False</span></code> is passed to <code class="docutils literal notranslate"><span class="pre">clone</span></code>.</p>
</div>
<div class="section" id="pipeline-compatibility">
<h3>Pipeline compatibility<a class="headerlink" href="#pipeline-compatibility" title="Permalink to this headline">¶</a></h3>
<p>For an estimator to be usable together with <code class="docutils literal notranslate"><span class="pre">pipeline.Pipeline</span></code> in any but the
last step, it needs to provide a <code class="docutils literal notranslate"><span class="pre">fit</span></code> or <code class="docutils literal notranslate"><span class="pre">fit_transform</span></code> function.
To be able to evaluate the pipeline on any data but the training set,
it also needs to provide a <code class="docutils literal notranslate"><span class="pre">transform</span></code> function.
There are no special requirements for the last step in a pipeline, except that
it has a <code class="docutils literal notranslate"><span class="pre">fit</span></code> function. All <code class="docutils literal notranslate"><span class="pre">fit</span></code> and <code class="docutils literal notranslate"><span class="pre">fit_transform</span></code> functions must
take arguments <code class="docutils literal notranslate"><span class="pre">X,</span> <span class="pre">y</span></code>, even if y is not used. Similarly, for <code class="docutils literal notranslate"><span class="pre">score</span></code> to be
usable, the last step of the pipeline needs to have a <code class="docutils literal notranslate"><span class="pre">score</span></code> function that
accepts an optional <code class="docutils literal notranslate"><span class="pre">y</span></code>.</p>
</div>
<div class="section" id="estimator-types">
<h3>Estimator types<a class="headerlink" href="#estimator-types" title="Permalink to this headline">¶</a></h3>
<p>Some common functionality depends on the kind of estimator passed.
For example, cross-validation in <a class="reference internal" href="../modules/generated/sklearn.model_selection.GridSearchCV.html#sklearn.model_selection.GridSearchCV" title="sklearn.model_selection.GridSearchCV"><code class="xref py py-class docutils literal notranslate"><span class="pre">model_selection.GridSearchCV</span></code></a> and
<a class="reference internal" href="../modules/generated/sklearn.model_selection.cross_val_score.html#sklearn.model_selection.cross_val_score" title="sklearn.model_selection.cross_val_score"><code class="xref py py-func docutils literal notranslate"><span class="pre">model_selection.cross_val_score</span></code></a> defaults to being stratified when used
on a classifier, but not otherwise. Similarly, scorers for average precision
that take a continuous prediction need to call <code class="docutils literal notranslate"><span class="pre">decision_function</span></code> for classifiers,
but <code class="docutils literal notranslate"><span class="pre">predict</span></code> for regressors. This distinction between classifiers and regressors
is implemented using the <code class="docutils literal notranslate"><span class="pre">_estimator_type</span></code> attribute, which takes a string value.
It should be <code class="docutils literal notranslate"><span class="pre">&quot;classifier&quot;</span></code> for classifiers and <code class="docutils literal notranslate"><span class="pre">&quot;regressor&quot;</span></code> for
regressors and <code class="docutils literal notranslate"><span class="pre">&quot;clusterer&quot;</span></code> for clustering methods, to work as expected.
Inheriting from <code class="docutils literal notranslate"><span class="pre">ClassifierMixin</span></code>, <code class="docutils literal notranslate"><span class="pre">RegressorMixin</span></code> or <code class="docutils literal notranslate"><span class="pre">ClusterMixin</span></code>
will set the attribute automatically.  When a meta-estimator needs to distinguish
among estimator types, instead of checking <code class="docutils literal notranslate"><span class="pre">_estimator_type</span></code> directly, helpers
like <a class="reference internal" href="../modules/generated/sklearn.base.is_classifier.html#sklearn.base.is_classifier" title="sklearn.base.is_classifier"><code class="xref py py-func docutils literal notranslate"><span class="pre">base.is_classifier</span></code></a> should be used.</p>
</div>
<div class="section" id="specific-models">
<h3>Specific models<a class="headerlink" href="#specific-models" title="Permalink to this headline">¶</a></h3>
<p>Classifiers should accept <code class="docutils literal notranslate"><span class="pre">y</span></code> (target) arguments to <code class="docutils literal notranslate"><span class="pre">fit</span></code> that are
sequences (lists, arrays) of either strings or integers.  They should not
assume that the class labels are a contiguous range of integers; instead, they
should store a list of classes in a <code class="docutils literal notranslate"><span class="pre">classes_</span></code> attribute or property.  The
order of class labels in this attribute should match the order in which
<code class="docutils literal notranslate"><span class="pre">predict_proba</span></code>, <code class="docutils literal notranslate"><span class="pre">predict_log_proba</span></code> and <code class="docutils literal notranslate"><span class="pre">decision_function</span></code> return their
values.  The easiest way to achieve this is to put:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="bp">self</span><span class="o">.</span><span class="n">classes_</span><span class="p">,</span> <span class="n">y</span> <span class="o">=</span> <span class="n">np</span><span class="o">.</span><span class="n">unique</span><span class="p">(</span><span class="n">y</span><span class="p">,</span> <span class="n">return_inverse</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>
</pre></div>
</div>
<p>in <code class="docutils literal notranslate"><span class="pre">fit</span></code>.  This returns a new <code class="docutils literal notranslate"><span class="pre">y</span></code> that contains class indexes, rather than
labels, in the range [0, <code class="docutils literal notranslate"><span class="pre">n_classes</span></code>).</p>
<p>A classifier’s <code class="docutils literal notranslate"><span class="pre">predict</span></code> method should return
arrays containing class labels from <code class="docutils literal notranslate"><span class="pre">classes_</span></code>.
In a classifier that implements <code class="docutils literal notranslate"><span class="pre">decision_function</span></code>,
this can be achieved with:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="k">def</span> <span class="nf">predict</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">X</span><span class="p">):</span>
    <span class="n">D</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">decision_function</span><span class="p">(</span><span class="n">X</span><span class="p">)</span>
    <span class="k">return</span> <span class="bp">self</span><span class="o">.</span><span class="n">classes_</span><span class="p">[</span><span class="n">np</span><span class="o">.</span><span class="n">argmax</span><span class="p">(</span><span class="n">D</span><span class="p">,</span> <span class="n">axis</span><span class="o">=</span><span class="mi">1</span><span class="p">)]</span>
</pre></div>
</div>
<p>In linear models, coefficients are stored in an array called <code class="docutils literal notranslate"><span class="pre">coef_</span></code>, and the
independent term is stored in <code class="docutils literal notranslate"><span class="pre">intercept_</span></code>.  <code class="docutils literal notranslate"><span class="pre">sklearn.linear_model._base</span></code>
contains a few base classes and mixins that implement common linear model
patterns.</p>
<p>The <code class="xref py py-mod docutils literal notranslate"><span class="pre">sklearn.utils.multiclass</span></code> module contains useful functions
for working with multiclass and multilabel problems.</p>
</div>
<div class="section" id="estimator-tags">
<span id="id3"></span><h3>Estimator Tags<a class="headerlink" href="#estimator-tags" title="Permalink to this headline">¶</a></h3>
<div class="admonition warning">
<p class="admonition-title">Warning</p>
<p>The estimator tags are experimental and the API is subject to change.</p>
</div>
<p>Scikit-learn introduced estimator tags in version 0.21.  These are annotations
of estimators that allow programmatic inspection of their capabilities, such as
sparse matrix support, supported output types and supported methods.  The
estimator tags are a dictionary returned by the method <code class="docutils literal notranslate"><span class="pre">_get_tags()</span></code>.  These
tags are used by the common tests and the <a class="reference internal" href="../modules/generated/sklearn.utils.estimator_checks.check_estimator.html#sklearn.utils.estimator_checks.check_estimator" title="sklearn.utils.estimator_checks.check_estimator"><code class="xref py py-func docutils literal notranslate"><span class="pre">sklearn.utils.estimator_checks.check_estimator</span></code></a> function to
decide what tests to run and what input data is appropriate. Tags can depend on
estimator parameters or even system architecture and can in general only be
determined at runtime.</p>
<p>The default value of all tags except for <code class="docutils literal notranslate"><span class="pre">X_types</span></code> and <code class="docutils literal notranslate"><span class="pre">requires_fit</span></code> is
<code class="docutils literal notranslate"><span class="pre">False</span></code>. These are defined in the <code class="docutils literal notranslate"><span class="pre">BaseEstimator</span></code> class.</p>
<p>The current set of estimator tags are:</p>
<dl class="simple">
<dt>non_deterministic</dt><dd><p>whether the estimator is not deterministic given a fixed <code class="docutils literal notranslate"><span class="pre">random_state</span></code></p>
</dd>
<dt>requires_positive_X</dt><dd><p>whether the estimator requires positive X.</p>
</dd>
<dt>requires_positive_y</dt><dd><p>whether the estimator requires a positive y (only applicable for regression).</p>
</dd>
<dt>no_validation</dt><dd><p>whether the estimator skips input-validation. This is only meant for stateless and dummy transformers!</p>
</dd>
<dt>multioutput - unused for now</dt><dd><p>whether a regressor supports multi-target outputs or a classifier supports multi-class multi-output.</p>
</dd>
<dt>multilabel</dt><dd><p>whether the estimator supports multilabel output</p>
</dd>
<dt>stateless</dt><dd><p>whether the estimator needs access to data for fitting. Even though
an estimator is stateless, it might still need a call to <code class="docutils literal notranslate"><span class="pre">fit</span></code> for initialization.</p>
</dd>
<dt>requires_fit</dt><dd><p>whether the estimator requires to be fitted before calling one of
<code class="docutils literal notranslate"><span class="pre">transform</span></code>, <code class="docutils literal notranslate"><span class="pre">predict</span></code>, <code class="docutils literal notranslate"><span class="pre">predict_proba</span></code>, or <code class="docutils literal notranslate"><span class="pre">decision_function</span></code>.</p>
</dd>
<dt>allow_nan</dt><dd><p>whether the estimator supports data with missing values encoded as np.NaN</p>
</dd>
<dt>poor_score</dt><dd><p>whether the estimator fails to provide a “reasonable” test-set score, which
currently for regression is an R2 of 0.5 on a subset of the boston housing
dataset, and for classification an accuracy of 0.83 on
<code class="docutils literal notranslate"><span class="pre">make_blobs(n_samples=300,</span> <span class="pre">random_state=0)</span></code>. These datasets and values
are based on current estimators in sklearn and might be replaced by
something more systematic.</p>
</dd>
<dt>multioutput_only</dt><dd><p>whether estimator supports only multi-output classification or regression.</p>
</dd>
<dt>binary_only</dt><dd><p>whether estimator supports binary classification but lacks multi-class
classification support.</p>
</dd>
<dt>_skip_test</dt><dd><p>whether to skip common tests entirely. Don’t use this unless you have a <em>very good</em> reason.</p>
</dd>
<dt>X_types</dt><dd><p>Supported input types for X as list of strings. Tests are currently only run if ‘2darray’ is contained
in the list, signifying that the estimator takes continuous 2d numpy arrays as input. The default
value is [‘2darray’]. Other possible types are <code class="docutils literal notranslate"><span class="pre">'string'</span></code>, <code class="docutils literal notranslate"><span class="pre">'sparse'</span></code>,
<code class="docutils literal notranslate"><span class="pre">'categorical'</span></code>, <code class="docutils literal notranslate"><span class="pre">dict</span></code>, <code class="docutils literal notranslate"><span class="pre">'1dlabels'</span></code> and <code class="docutils literal notranslate"><span class="pre">'2dlabels'</span></code>.
The goal is that in the future the supported input type will determine the
data used during testing, in particular for <code class="docutils literal notranslate"><span class="pre">'string'</span></code>, <code class="docutils literal notranslate"><span class="pre">'sparse'</span></code> and
<code class="docutils literal notranslate"><span class="pre">'categorical'</span></code> data.  For now, the test for sparse data do not make use
of the <code class="docutils literal notranslate"><span class="pre">'sparse'</span></code> tag.</p>
</dd>
</dl>
<p>To override the tags of a child class, one must define the <code class="docutils literal notranslate"><span class="pre">_more_tags()</span></code>
method and return a dict with the desired tags, e.g:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="k">class</span> <span class="nc">MyMultiOutputEstimator</span><span class="p">(</span><span class="n">BaseEstimator</span><span class="p">):</span>

    <span class="k">def</span> <span class="nf">_more_tags</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
        <span class="k">return</span> <span class="p">{</span><span class="s1">&#39;multioutput_only&#39;</span><span class="p">:</span> <span class="kc">True</span><span class="p">,</span>
                <span class="s1">&#39;non_deterministic&#39;</span><span class="p">:</span> <span class="kc">True</span><span class="p">}</span>
</pre></div>
</div>
<p>In addition to the tags, estimators also need to declare any non-optional
parameters to <code class="docutils literal notranslate"><span class="pre">__init__</span></code> in the <code class="docutils literal notranslate"><span class="pre">_required_parameters</span></code> class attribute,
which is a list or tuple.  If <code class="docutils literal notranslate"><span class="pre">_required_parameters</span></code> is only
<code class="docutils literal notranslate"><span class="pre">[&quot;estimator&quot;]</span></code> or <code class="docutils literal notranslate"><span class="pre">[&quot;base_estimator&quot;]</span></code>, then the estimator will be
instantiated with an instance of <code class="docutils literal notranslate"><span class="pre">LinearDiscriminantAnalysis</span></code> (or
<code class="docutils literal notranslate"><span class="pre">RidgeRegression</span></code> if the estimator is a regressor) in the tests. The choice
of these two models is somewhat idiosyncratic but both should provide robust
closed-form solutions.</p>
</div>
</div>
<div class="section" id="coding-guidelines">
<span id="id4"></span><h2>Coding guidelines<a class="headerlink" href="#coding-guidelines" title="Permalink to this headline">¶</a></h2>
<p>The following are some guidelines on how new code should be written for
inclusion in scikit-learn, and which may be appropriate to adopt in external
projects. Of course, there are special cases and there will be exceptions to
these rules. However, following these rules when submitting new code makes
the review easier so new code can be integrated in less time.</p>
<p>Uniformly formatted code makes it easier to share code ownership. The
scikit-learn project tries to closely follow the official Python guidelines
detailed in <a class="reference external" href="https://www.python.org/dev/peps/pep-0008">PEP8</a> that
detail how code should be formatted and indented. Please read it and
follow it.</p>
<p>In addition, we add the following guidelines:</p>
<ul class="simple">
<li><p>Use underscores to separate words in non class names: <code class="docutils literal notranslate"><span class="pre">n_samples</span></code>
rather than <code class="docutils literal notranslate"><span class="pre">nsamples</span></code>.</p></li>
<li><p>Avoid multiple statements on one line. Prefer a line return after
a control flow statement (<code class="docutils literal notranslate"><span class="pre">if</span></code>/<code class="docutils literal notranslate"><span class="pre">for</span></code>).</p></li>
<li><p>Use relative imports for references inside scikit-learn.</p></li>
<li><p>Unit tests are an exception to the previous rule;
they should use absolute imports, exactly as client code would.
A corollary is that, if <code class="docutils literal notranslate"><span class="pre">sklearn.foo</span></code> exports a class or function
that is implemented in <code class="docutils literal notranslate"><span class="pre">sklearn.foo.bar.baz</span></code>,
the test should import it from <code class="docutils literal notranslate"><span class="pre">sklearn.foo</span></code>.</p></li>
<li><p><strong>Please don’t use</strong> <code class="docutils literal notranslate"><span class="pre">import</span> <span class="pre">*</span></code> <strong>in any case</strong>. It is considered harmful
by the <a class="reference external" href="https://docs.python.org/3.1/howto/doanddont.html#at-module-level">official Python recommendations</a>.
It makes the code harder to read as the origin of symbols is no
longer explicitly referenced, but most important, it prevents
using a static analysis tool like <a class="reference external" href="https://divmod.readthedocs.io/en/latest/products/pyflakes.html">pyflakes</a> to automatically
find bugs in scikit-learn.</p></li>
<li><p>Use the <a class="reference external" href="https://numpy.readthedocs.io/en/latest/format.html">numpy docstring standard</a> in all your docstrings.</p></li>
</ul>
<p>A good example of code that we like can be found <a class="reference external" href="https://gist.github.com/nateGeorge/5455d2c57fb33c1ae04706f2dc4fee01">here</a>.</p>
<div class="section" id="input-validation">
<h3>Input validation<a class="headerlink" href="#input-validation" title="Permalink to this headline">¶</a></h3>
<p>The module <a class="reference internal" href="../modules/classes.html#module-sklearn.utils" title="sklearn.utils"><code class="xref py py-mod docutils literal notranslate"><span class="pre">sklearn.utils</span></code></a> contains various functions for doing input
validation and conversion. Sometimes, <code class="docutils literal notranslate"><span class="pre">np.asarray</span></code> suffices for validation;
do <em>not</em> use <code class="docutils literal notranslate"><span class="pre">np.asanyarray</span></code> or <code class="docutils literal notranslate"><span class="pre">np.atleast_2d</span></code>, since those let NumPy’s
<code class="docutils literal notranslate"><span class="pre">np.matrix</span></code> through, which has a different API
(e.g., <code class="docutils literal notranslate"><span class="pre">*</span></code> means dot product on <code class="docutils literal notranslate"><span class="pre">np.matrix</span></code>,
but Hadamard product on <code class="docutils literal notranslate"><span class="pre">np.ndarray</span></code>).</p>
<p>In other cases, be sure to call <a class="reference internal" href="../modules/generated/sklearn.utils.check_array.html#sklearn.utils.check_array" title="sklearn.utils.check_array"><code class="xref py py-func docutils literal notranslate"><span class="pre">check_array</span></code></a> on any array-like argument
passed to a scikit-learn API function. The exact parameters to use depends
mainly on whether and which <code class="docutils literal notranslate"><span class="pre">scipy.sparse</span></code> matrices must be accepted.</p>
<p>For more information, refer to the <a class="reference internal" href="utilities.html#developers-utils"><span class="std std-ref">Utilities for Developers</span></a> page.</p>
</div>
<div class="section" id="random-numbers">
<h3>Random Numbers<a class="headerlink" href="#random-numbers" title="Permalink to this headline">¶</a></h3>
<p>If your code depends on a random number generator, do not use
<code class="docutils literal notranslate"><span class="pre">numpy.random.random()</span></code> or similar routines.  To ensure
repeatability in error checking, the routine should accept a keyword
<code class="docutils literal notranslate"><span class="pre">random_state</span></code> and use this to construct a
<code class="docutils literal notranslate"><span class="pre">numpy.random.RandomState</span></code> object.
See <a class="reference internal" href="../modules/generated/sklearn.utils.check_random_state.html#sklearn.utils.check_random_state" title="sklearn.utils.check_random_state"><code class="xref py py-func docutils literal notranslate"><span class="pre">sklearn.utils.check_random_state</span></code></a> in <a class="reference internal" href="utilities.html#developers-utils"><span class="std std-ref">Utilities for Developers</span></a>.</p>
<p>Here’s a simple example of code using some of the above guidelines:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">sklearn.utils</span> <span class="kn">import</span> <span class="n">check_array</span><span class="p">,</span> <span class="n">check_random_state</span>

<span class="k">def</span> <span class="nf">choose_random_sample</span><span class="p">(</span><span class="n">X</span><span class="p">,</span> <span class="n">random_state</span><span class="o">=</span><span class="mi">0</span><span class="p">):</span>
    <span class="sd">&quot;&quot;&quot;</span>
<span class="sd">    Choose a random point from X</span>

<span class="sd">    Parameters</span>
<span class="sd">    ----------</span>
<span class="sd">    X : array-like, shape (n_samples, n_features)</span>
<span class="sd">        array representing the data</span>
<span class="sd">    random_state : RandomState or an int seed (0 by default)</span>
<span class="sd">        A random number generator instance to define the state of the</span>
<span class="sd">        random permutations generator.</span>

<span class="sd">    Returns</span>
<span class="sd">    -------</span>
<span class="sd">    x : numpy array, shape (n_features,)</span>
<span class="sd">        A random point selected from X</span>
<span class="sd">    &quot;&quot;&quot;</span>
    <span class="n">X</span> <span class="o">=</span> <span class="n">check_array</span><span class="p">(</span><span class="n">X</span><span class="p">)</span>
    <span class="n">random_state</span> <span class="o">=</span> <span class="n">check_random_state</span><span class="p">(</span><span class="n">random_state</span><span class="p">)</span>
    <span class="n">i</span> <span class="o">=</span> <span class="n">random_state</span><span class="o">.</span><span class="n">randint</span><span class="p">(</span><span class="n">X</span><span class="o">.</span><span class="n">shape</span><span class="p">[</span><span class="mi">0</span><span class="p">])</span>
    <span class="k">return</span> <span class="n">X</span><span class="p">[</span><span class="n">i</span><span class="p">]</span>
</pre></div>
</div>
<p>If you use randomness in an estimator instead of a freestanding function,
some additional guidelines apply.</p>
<p>First off, the estimator should take a <code class="docutils literal notranslate"><span class="pre">random_state</span></code> argument to its
<code class="docutils literal notranslate"><span class="pre">__init__</span></code> with a default value of <code class="docutils literal notranslate"><span class="pre">None</span></code>.
It should store that argument’s value, <strong>unmodified</strong>,
in an attribute <code class="docutils literal notranslate"><span class="pre">random_state</span></code>.
<code class="docutils literal notranslate"><span class="pre">fit</span></code> can call <code class="docutils literal notranslate"><span class="pre">check_random_state</span></code> on that attribute
to get an actual random number generator.
If, for some reason, randomness is needed after <code class="docutils literal notranslate"><span class="pre">fit</span></code>,
the RNG should be stored in an attribute <code class="docutils literal notranslate"><span class="pre">random_state_</span></code>.
The following example should make this clear:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="k">class</span> <span class="nc">GaussianNoise</span><span class="p">(</span><span class="n">BaseEstimator</span><span class="p">,</span> <span class="n">TransformerMixin</span><span class="p">):</span>
    <span class="sd">&quot;&quot;&quot;This estimator ignores its input and returns random Gaussian noise.</span>

<span class="sd">    It also does not adhere to all scikit-learn conventions,</span>
<span class="sd">    but showcases how to handle randomness.</span>
<span class="sd">    &quot;&quot;&quot;</span>

    <span class="k">def</span> <span class="fm">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">n_components</span><span class="o">=</span><span class="mi">100</span><span class="p">,</span> <span class="n">random_state</span><span class="o">=</span><span class="kc">None</span><span class="p">):</span>
        <span class="bp">self</span><span class="o">.</span><span class="n">random_state</span> <span class="o">=</span> <span class="n">random_state</span>

    <span class="c1"># the arguments are ignored anyway, so we make them optional</span>
    <span class="k">def</span> <span class="nf">fit</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">X</span><span class="o">=</span><span class="kc">None</span><span class="p">,</span> <span class="n">y</span><span class="o">=</span><span class="kc">None</span><span class="p">):</span>
        <span class="bp">self</span><span class="o">.</span><span class="n">random_state_</span> <span class="o">=</span> <span class="n">check_random_state</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">random_state</span><span class="p">)</span>

    <span class="k">def</span> <span class="nf">transform</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">X</span><span class="p">):</span>
        <span class="n">n_samples</span> <span class="o">=</span> <span class="n">X</span><span class="o">.</span><span class="n">shape</span><span class="p">[</span><span class="mi">0</span><span class="p">]</span>
        <span class="k">return</span> <span class="bp">self</span><span class="o">.</span><span class="n">random_state_</span><span class="o">.</span><span class="n">randn</span><span class="p">(</span><span class="n">n_samples</span><span class="p">,</span> <span class="n">n_components</span><span class="p">)</span>
</pre></div>
</div>
<p>The reason for this setup is reproducibility:
when an estimator is <code class="docutils literal notranslate"><span class="pre">fit</span></code> twice to the same data,
it should produce an identical model both times,
hence the validation in <code class="docutils literal notranslate"><span class="pre">fit</span></code>, not <code class="docutils literal notranslate"><span class="pre">__init__</span></code>.</p>
</div>
</div>
</div>


      </div>
    <div class="container">
      <footer class="sk-content-footer">
            &copy; 2007 - 2019, scikit-learn developers (BSD License).
          <a href="../_sources/developers/develop.rst.txt" rel="nofollow">Show this page source</a>
      </footer>
    </div>
  </div>
</div>
<script src="../_static/js/vendor/bootstrap.min.js"></script>

<script>
    window.ga=window.ga||function(){(ga.q=ga.q||[]).push(arguments)};ga.l=+new Date;
    ga('create', 'UA-22606712-2', 'auto');
    ga('set', 'anonymizeIp', true);
    ga('send', 'pageview');
</script>
<script async src='https://www.google-analytics.com/analytics.js'></script>


<script>
$(document).ready(function() {
    /* Add a [>>>] button on the top-right corner of code samples to hide
     * the >>> and ... prompts and the output and thus make the code
     * copyable. */
    var div = $('.highlight-python .highlight,' +
                '.highlight-python3 .highlight,' +
                '.highlight-pycon .highlight,' +
		'.highlight-default .highlight')
    var pre = div.find('pre');

    // get the styles from the current theme
    pre.parent().parent().css('position', 'relative');
    var hide_text = 'Hide prompts and outputs';
    var show_text = 'Show prompts and outputs';

    // create and add the button to all the code blocks that contain >>>
    div.each(function(index) {
        var jthis = $(this);
        if (jthis.find('.gp').length > 0) {
            var button = $('<span class="copybutton">&gt;&gt;&gt;</span>');
            button.attr('title', hide_text);
            button.data('hidden', 'false');
            jthis.prepend(button);
        }
        // tracebacks (.gt) contain bare text elements that need to be
        // wrapped in a span to work with .nextUntil() (see later)
        jthis.find('pre:has(.gt)').contents().filter(function() {
            return ((this.nodeType == 3) && (this.data.trim().length > 0));
        }).wrap('<span>');
    });

    // define the behavior of the button when it's clicked
    $('.copybutton').click(function(e){
        e.preventDefault();
        var button = $(this);
        if (button.data('hidden') === 'false') {
            // hide the code output
            button.parent().find('.go, .gp, .gt').hide();
            button.next('pre').find('.gt').nextUntil('.gp, .go').css('visibility', 'hidden');
            button.css('text-decoration', 'line-through');
            button.attr('title', show_text);
            button.data('hidden', 'true');
        } else {
            // show the code output
            button.parent().find('.go, .gp, .gt').show();
            button.next('pre').find('.gt').nextUntil('.gp, .go').css('visibility', 'visible');
            button.css('text-decoration', 'none');
            button.attr('title', hide_text);
            button.data('hidden', 'false');
        }
    });

	/*** Add permalink buttons next to glossary terms ***/
	$('dl.glossary > dt[id]').append(function() {
		return ('<a class="headerlink" href="#' +
			    this.getAttribute('id') +
			    '" title="Permalink to this term">¶</a>');
	});
  /*** Hide navbar when scrolling down ***/
  // Returns true when headerlink target matches hash in url
  (function() {
    hashTargetOnTop = function() {
        var hash = window.location.hash;
        if ( hash.length < 2 ) { return false; }

        var target = document.getElementById( hash.slice(1) );
        if ( target === null ) { return false; }

        var top = target.getBoundingClientRect().top;
        return (top < 2) && (top > -2);
    };

    // Hide navbar on load if hash target is on top
    var navBar = document.getElementById("navbar");
    var navBarToggler = document.getElementById("sk-navbar-toggler");
    var navBarHeightHidden = "-" + navBar.getBoundingClientRect().height + "px";
    var $window = $(window);

    hideNavBar = function() {
        navBar.style.top = navBarHeightHidden;
    };

    showNavBar = function() {
        navBar.style.top = "0";
    }

    if (hashTargetOnTop()) {
        hideNavBar()
    }

    var prevScrollpos = window.pageYOffset;
    hideOnScroll = function(lastScrollTop) {
        if (($window.width() < 768) && (navBarToggler.getAttribute("aria-expanded") === 'true')) {
            return;
        }
        if (lastScrollTop > 2 && (prevScrollpos <= lastScrollTop) || hashTargetOnTop()){
            hideNavBar()
        } else {
            showNavBar()
        }
        prevScrollpos = lastScrollTop;
    };

    /*** high preformance scroll event listener***/
    var raf = window.requestAnimationFrame ||
        window.webkitRequestAnimationFrame ||
        window.mozRequestAnimationFrame ||
        window.msRequestAnimationFrame ||
        window.oRequestAnimationFrame;
    var lastScrollTop = $window.scrollTop();

    if (raf) {
        loop();
    }

    function loop() {
        var scrollTop = $window.scrollTop();
        if (lastScrollTop === scrollTop) {
            raf(loop);
            return;
        } else {
            lastScrollTop = scrollTop;
            hideOnScroll(lastScrollTop);
            raf(loop);
        }
    }
  })();
});

</script>
    
<script id="MathJax-script" async src="https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-chtml.js"></script>
    
</body>
</html>